CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / LSAM.ZIP / LSAM.DOC < prev next >

Wrap

Text File | 1988-02-22 | 40.9 KB | 828 lines

GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - CONTENTS - - -| |___________________________________________| Notice to users .................. 0 Introduction ..................... 1 System overview .................. 2 System requirements .............. 4 Storage requirements ............. 5 Function summary ................. 6 Header files ..................... 7 Function descriptions ............ 8 Linking programs ................. 11 Support programs ................. 12 Runtime control variables ........ 15 GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - NOTICE TO USERS - - -| |___________________________________________| page 0H You have received a disabled version of LSAM with this documen- tation. REGARDLESS OF WHAT MAY BE STATED ELSEWHERE IN THIS DOC- UMENT, THE SYSTEM WILL ALLOW ONLY 3 (THREE) INDEX FILES TO BE ALLOCATED. This will serve to allow the user to try the system in a simple 'test' application. Any attempt at usage of this demo beyond 3 index files will result in a return of RMAXFIL to the 'test' application (though many 'production' applications will require a total of 3 or fewer indices for 1 to 3 base files). You may feel free to use this demo system free of charge and to dis- tribute the RTL and associated parm files to any of your friends and/or users without obligation. Should you find this product of use and wish to purchase a full-function, licensed copy, or if you wish more information, you should contact me via CompuServe's EasyPlex or GEnie's mail: Craig J. Starr d/b/a Lydian Software CompuServe userid 72617,1345 GEnie mail address C.STARR I will be happy to answer any of your questions. The software will pro- bably be available soon via SOFTEX. Arrangements are not complete at the moment. If you contact me, I will be happpy to provide you with the latest details regarding availability and PRICE, WHICH I WILL MAKE EVERY EFFORT TO HOLD BELOW THE $80.00 LEVEL FOR THIS RELEASE. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - INTRODUCTION - - -| |___________________________________________| page 1H LSAM (Lydian Software Access Method) V2.02 is an indexed sequential (ISAM) file access method implemented as a runtime library accessed through a set of interface subroutines for users of Microsoft (3.x +) compilers. Its price is significantly below that of the lowest discoun- ted-price b+tree indexed file access method packages available up to now, but its function and ease of use make it formidable competition for it's higher-priced cousins. It is an ideal choice for the appli- cation programmer who needs a full-function, high-performance indexed file access method at a reasonable price. It features support for multiple indices per base file, insertion, deletion (logical), retrieval and update by 'key', and full (logical) sequential processing capability in both directions, including (re-) positioning of a file's internal current record pointer for sequential processing of a record (or group of records) beginning at any logical record location in the file. For a more detailed discussion of the particulars of the system's function and logic, see the section entitled 'SYSTEM OVERVIEW.' LSAM is supplied in the form of 4 relocatable object libraries, one for each of the standard memory models supported by Microsoft C 3.x, 1 exe- cutable overlay module (referred to as 'the runtime'), 5 ASCII text files (three containing required source statements, one containing sam- ple source for a typical parameter file generation, one containing this documentation), and 2 standalone programs which support the generation and formatted display of the binary image parameter files used to define the attributes of the base/index file combinations to the runtime system, all compressed into a '.arc' format file by the program "ARC", which must be used to extract them. There are 12 files supplied in total. The files contained in this archive are: G system files --------------------------------------------------------- *** files required for compiling, linking and generating *** *** programs and data which will make use of the LSAM system*** slsam4.lib system subroutine library - 4.0 small model clsam4.lib system subroutine library - 4.0 compact model mlsam4.lib system subroutine library - 4.0 medium model llsam4.lib system subroutine library - 4.0 large model slsam5.lib system subroutine library - 5.0 small model clsam5.lib system subroutine library - 5.0 compact model mlsam5.lib system subroutine library - 5.0 medium model llsam5.lib system subroutine library - 5.0 large model lsam.rtl system runtime support library genparm.exe system parameter file generation utility parmlist.exe system parameter file display utility lsam.h required header file (user data structures) lsrcodes.h required header file (return code #defines) lslimits.h required header file (key, path length ctl) lsam.doc this documentation demo files ----------------------------------------------------------- *** a sample program, plus sample data and parm file inputs *** *** see comment header in bkup.c for usage and suggestions *** bkup.c sample source (a backup) using LSAM calls pgm bkup.exe sample executable program for bkup.c above sample.txt sample parameter file ASCII source input sample.bin sample generated binary parameter file input sample.dat sample data file (as specified in sample.txt) sampleb.txt sample backup parameter file ASCII source input sampleb.bin sample backup generated binary parameter file H GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SYSTEM OVERVIEW - - -| |___________________________________________| page 2H LSAM is composed of two major components, a runtime support 'overlay' module and a subroutine function-request interface package. The sub- routines are the only code linked into the application program. The 'runtime' support code is loaded into dynamically allocated storage on the first 'open' call (ls_open()). It is subsequently called at its various entry points whenever one of the LSAM subroutines is called, passing the appropriate request parameters. At system exit time, it is then called with a request to free any storage it has allocated, and when this call returns, the storage allocated for loading the runtime code is returned to DOS. The runtime code is thus technically a 'part- time' runtime library (RTL), since it occupies storage only from the application's first open call until the application calls the system exit routine ls_exit() (this is why IT IS IMPERATIVE THAT ANY CALLS TO EXIT() WHICH WOULD BE ISSUED AFTER THE FIRST OPEN CALL BE REPLACED BY CALLS TO LS_EXIT() ). The benefits of this approach are that 1) the 20+K of code in the RTL is NOT LINKED INTO ANY APPLICATION PROGRAM which uses it, saving on application code disk space requirements, and 2) en- hancements, updates, and fixes to the RTL do not require recompilation of existing application programs, but rather shipment of a revised RTL to application developers, who may in turn ship copies to the licensed users of their systems. LSAM is implemented with a 'separate index' philosophy. That is, it does not intermingle the ind(ex/ices) and the user's data, which remains as a standard sequential binary (fixed-length record - ver. 2.02) file, capable of being processed as such by any non-LSAM application. Since LSAM is not 'wired-in' to the user's data, it may easily be fitted to existing applications with existing user data files with NO CONVERSION OF DATA REQUIRED, by simply generating the required parm file(s) and re- placing I/O routine calls with the corresponding LSAM subroutine calls. LSAM can open (or create, if [it does/they do] not exist) and use any number of indices for any number of base files (within the confines of available storage - see 'STORAGE REQUIREMENTS'). Logical record length may be up to 64K (65536) bytes, but must be of fixed length for rel. 2.02. Keys are limited to a total of 255 bytes in length, and may be 'split,' i.e. comprised of multiple non-contiguous fields in the user record. The b+tree index management internals in the runtime system can support index entries for files of up to 2 ** 32 (4,294,967,296) user logical records. However, the multiple base file seeks required for relative byte offsets greater than the number above have not yet been implemented in the LSAM functions to which the user has access, so the current practical upward limit is ((2 ** 32) / (user lrecl)) records. The system is parameter-file driven in that it uses, for each base/index file group, a generated binary image file, which tells LSAM the charac- teristics of the data and index files it will open and process, such as the file/index pathname, logical record length, location in the logical record of key field(s), and several other attributes, discussed in full under the section entitled 'SUPPORT PROGRAMS.' This allows the program- mer to isolate from the application such details as key field length and position, file name, path name, and other information which may change periodically, without being required to recode or recompile the application program. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SYSTEM OVERVIEW - - -| |___________________________________________| page 3H LSAM's control blocks are built at base/index file set open time from binary parameter files (one each per base/index file set). The open routine returns a pointer to an internal control block, which the user will pass to the various other interface routines along with other parameters. The binary parameter files are generated by the standalone program genparm.exe using ASCII text source input similar in format to the 'keyword=parm,keyword2=parm2' format characteristic of IBM mainframe system software generation/configuration macros, although somewhat more free form. The parameters and their coding requirements are documented more fully under the section 'SUPPORT PROGRAMS.' Sample text for such a parameter file (sample.txt) is included in the package. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SYSTEM REQUIREMENTS - - -| |___________________________________________| page 4H Application developers using LSAM will require (on their own and their target user systems): 128K RAM Minimum (assuming no add-on memory-resident programs and a very small LSAMIXALLOC value) DOS 3.0 or higher ** A hard disk is also preferred but not required Developers themselves will require: Microsoft C compiler (release 4.0 or higher) GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - STORAGE REQUIREMENTS - - -| |___________________________________________| page 5H The user (application programmer) controls the ultimate (potential) storage requirements of LSAM through the DOS environment variable LSAMIXALLOC, which (see section entitled 'RUNTIME CONTROL VARIABLES') specifies the number of index control blocks to allocate at startup time. The storage required for each control block is, in version 2.02, 36 bytes. In addition, buffers totaling either 3K, 6K, or 12K are allocated at open time for each index file opened by the runtime system, depending on the length of the key (keylengths 1-64 cause 3K of buffers to be allocated, keylengths 65-128 will use 6K of buffers, and 129-255 will use 12K of buffers). These factors must be considered in planning the design of any application system which is to make effective use of LSAM. As an example, if the largest application your user will run uses 16 in- dex files and they will all be open at the same time and have keylengths less than 65, control blocks will require 16 times 36 bytes = 576 bytes for internal control blocks (allocated as a block at startup), plus 16 times 3K bytes = 49152 bytes for buffer space, for a total allocation of 49728 bytes in addition to the requirements (check your program with Microsoft's EXEMOD utility) of your program and the roughly 30K bytes required for the load of the runtime system: 16 ctl blocks 576 bytes 16 3K buffers 49152 bytes runtime stge. 30000 bytes avg user pgm. 25000 bytes ----- total required 104728 bytes for this application GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - FUNCTION SUMMARY - - -| |___________________________________________| page 6H The following is a list of the functions available to the user of the LSAM system. Full descriptions follow in the FUNCTION DESCRIPTION section. void ls_bldixkey(); /* build key string service for non-contiguous keys */ int ls_is_ix_new(), /* returns YES if selected ix created by this run, else NO */ ls_bldindx(), /* build index file for given base file */ ls_startbr(), /* (re)set internal current record pointer for seq read */ ls_read(), /* 'key' read - 'random' retrieval of logical record */ ls_readnext(), /* sequential read (next) logical record, given index */ ls_readprev(), /* sequential read (prev) logical record, given index */ ls_write(), /* write new record */ ls_rewrite(), /* update existing record */ ls_delete(), /* delete existing record */ ls_close(), /* close base/index file set */ lsam(); /* dummy call to force linker inclusion of lsam module */ LSBFPP ls_open(); /* open base/index file set using generated parm file */ GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - HEADER FILES - - -| |___________________________________________| page 7H Three header files are supplied with LSAM: "lsam.h", "lsrcodes.h", and "lslimits.h", which are to be included via the #include compiler directive in any source modules which make reference to any LSAM function or symbolic name (i.e. a manifest constant such as the return code constant value RGOOD). Since LSAM.H contains '#include's for LSRCODES.H and LSLIMITS.H, the application programmer need only code the required '#include' for LSAM.H. Put these files in a subdirectory which the compiler will search when it compiles your programs. LSAM.H contains the data structure definitions and symbolic constants for various request parameter values required to use LSAM, plus the declarations of all the functions available in the system. LSRCODES.H contains the symbolic constants (#defines) for the LSAM system return codes. Since these values may change in a future re- lease, the user is STRONGLY advised to USE THE NAMES when testing re- turn codes for specific values. They will not change from release to release. This will simplify maintenance to your source when upgrading to a future release. LSLIMITS.H contains the symbolic constants (#defines) for the LSAM field size limits: maximum keylength and maximum pathname length. As with LSRCODES.H above, the user would be well advised to use these symbolic names rather than hard-code numeric values, for the same common-sense reasons of maintainability. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - FUNCTION DESCRIPTIONS - - -| |___________________________________________| page 8H By using the interface subroutine oriented approach, most calls to the LSAM functions simply pass the LSBFPP pointer, an index no., key, and the system routines take care of the required control block manipu- lation, thereby simplifying the programmer's task. Zero return codes are OK for all except ls_open(), which should return the address of the control block it allocates. Other return codes re- present error conditions and should be handled appropriately (with the exception of REOF, which may be ignored if the programmer desires to "wrap-around" to the logical beginning or end of the file). lsam() /* dummy call */ This function is a do-nothing routine supplied to en- able the user to force the linker to include the lsam.obj module which contains all of the routines described below. The user simply codes a dummy routine which calls lsam(), then NEVER CALLS THIS DUMMY routine. The linker automatically will include the lsam.obj module. There is no harm done, other than the waste of a few machine cycles, if the user inadvertently calls lsam(). It will just return. Example of dummy call usage: dummy() /* This routine is NOT called anywhere in pgm */ { lsam(); /* This will fool the linker into including lsam.obj */ } As an alternative to a dummy call, the user may (must) specify the name 'lsam' explicitly to the linker, in the object modules list, which means, of course, that lsam.obj must be extracted from lsam.lib with lib.exe (Microsoft or equivalent object library manager) prior to linking in this alternative manner. int ls_is_ix_new(base,ix) /* RETURNS YES IF INDEX WAS CREATED BY THIS RUN */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index selected */ ls_open() sets internal control codes for each index file successfully opened. Use this routine to check the status of a particular index file to determine if it was just created. The routine ls_bldindx() also checks this status and exits if it is not YES. Should you wish to re- build an existing index file, you must delete it from DOS before running your application program, which should have a call to this routine and a corresponding conditional call to ls_bldindx() for each index file you wish to rebuild. Usage example: if(ls_is_ix_new(base,ix) == YES) /* did LSAM just create this ix ?*/ ls_bldindx(base,ix); /* then ask LSAM to build it */ int ls_bldindx(base,ix) /*CREATES AND BUILDS AN INDEX FILE FOR GIVEN BASE FILE*/ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be built */ Value "ix" is the table subscript of the index to build. Valid values are 0 through the number of indices you 'genned' in your parameter file minus 1 (i.e. they are relative subscript numbers) and CORRESPOND DIRECT- LY to the order in which you specified them in the text of the parm file. NOTE: ls_open() sets internal control codes for each index file successfully opened. ls_bldindx() checks one of these before proceeding and exits if it indicates that the index file is not new/empty. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - FUNCTION DESCRIPTIONS - - -| |___________________________________________| page 9H void ls_bldixkey(base,ix,key) /*BUILD INDEX KEY FIELD FROM RECORD KEY FIELD(S)*/ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ UCHAR *key; /* pointer to user key work array */ Since the functions which require keys take a single address value for the key, it is necessary to concatenate any split key sub-fields before calling a routine which requires a key field address. This routine uses register pointer variables and is very fast. THIS ROUTINE IS OF NO USE FOR ANY OF YOUR INDICES FOR WHICH THE RECORD KEY IS ONE CONTI- GUOUS AREA IN THE RECORD. FOR SUCH KEYS, THE ADDRESS OF THE KEY FIELD WITHIN THE USER RECORD IS A VALID KEY POINTER, AND YOU WILL SAVE THE PROCESSING OVERHEAD OF THIS CALL. NOTE: This special function provides a service to concatenate split key sub-fields from a user record into a user key work area, the address of which may then be passed to any LSAM routine requiring a key field address. User key work area(s) MUST BE LONG ENOUGH to contain the key length used by the index referenced in the call. This routine can NOT verify user key work area length, and will write until all key sub-fields are copied, potentially clobbering adjacent data. To play it safe, you can make your key field work area(s) 256 bytes long, one byte longer than the maximum key length (255), which the parameter file generation program 'genparm.exe' dictates. int ls_startbr(base,ix,key,stype) /* START BROWSE - POSITION IN FILE VIA IX */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ UCHAR *key; /* pointer to user key work array */ UCHAR stype; /* type of start: GTEQ or EQUAL */ (High-order, i.e. leftmost) Partial keys may be used if stype = GTEQ is specified. Position will be at logical record with next greater or equal record key value. Return will be RGOOD regardless of whether the key found is greater than or equal to the requested key field. If EQUAL is specified, full key should be supplied because the runtime searches for an EXACT match. In this case, if an exact match is not found, the runtime returns RNOTFND and the current record pointer remains where it was. int ls_read(base,ix,key) /* READ 'RANDOM' BY KEY */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ UCHAR *key; /* pointer to user key work array */ int ls_readnext(base,ix) /* READ NEXT LOGICALLY SEQ. FILE RECORD */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ Return value REOF may be ignored if desired. The first logical record in the dataset will be in the user record area on return. int ls_readprev(base,ix) /* READ PREV LOGICALLY SEQ. FILE RECORD */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ Return value REOF may be ignored if desired. The last logical record in the dataset will be in the user record area on return. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - FUNCTION DESCRIPTIONS - - -| |___________________________________________| page 10H int ls_write(base) /* WRITE A NEW RECORD */ LSBFPP base; /* pointer to base file info structure */ Appends a new record to the base dataset, and inserts an index entry into ALL indices for which the UPGRADE=yes option was specified in its parameter file generation. If UNIQUEKEY=yes was specified in its parameter file, error RDUPKEY is returned if an entry for the key is already present in an index for which UPGRADE=yes is in effect. int ls_rewrite(base,ix,key) /* REWRITE AN EXISTING RECORD */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ UCHAR *key; /* pointer to user key work array */ int ls_delete(base,ix,key) /* DELETE AN EXISTING (INDEX) RECORD */ LSBFPP base; /* pointer to base file info structure */ UINT ix; /* relative subscript of index to be used */ UCHAR *key; /* pointer to user key work array */ This is a 'logical' delete. ONLY THE SELECTED INDEX RECORD IS DELETED, thereby allowing a measure of recovery (by rebuilding the index file). LSBFPP ls_open(parm,env_or_name,mode,recptr) /*OPEN BASE FILE & RELATED INDICES*/ UCHAR *parm; /* pointer to parm file ENV VAR or NAME */ int env_or_name; /* switch (YES/NO) is parm ENV or NAME ? */ UCHAR *mode; /* mode same as fopen() - 'BINARY' SEE DOC. */ UCHAR *recptr; /* address of user record area */ If the base file open succeeds, this function attempts to open all related index files. All buffers required for each index group are allocated by the runtime system at this time. The user MUST specify a binary-mode open for this call (e.g. "w+b" "r+b" "wb" "rb" - see fopen()). If not, base file positioning is NOT guaranteed to be accurate. NOTE: ON THE FIRST CALL TO ls_open(), THE RUNTIME CODE IS LOADED. ANY CALLS TO OTHER INTERFACE ROUTINES BEFORE THIS WILL RESULT IN A RETURN OF RINITERR (Initialization error, the b+tree runtime library code has not been loaded). NOTE: A NULL (ZERO) RETURN FOR ls_open() IS AN ERROR, AS WITH FOPEN(). --------------------------------------------------------------------- int ls_close(base) /* CLOSE BASE FILE AND ITS RELATED INDICES */ LSBFPP base; /* pointer to base file info structure */ This function will close all related index files for a base dataset, then close the base via fclose(). All buffers allocated by the runtime system for this index group are de-allocated at this time. Return values are the same as for fclose(). int ls_exit() /* REQUIRED AS LAST REQUEST -- MUST CALL TO FREE RTL MEMORY */ This function will signal the RTL to release its acquired memory, then release the memory into which the RTL was loaded, then call the standard C exit routine exit(). It does not return. RESULTS ARE UNPREDICTABLE IF THIS ROUTINE IS NOT CALLED AS YOUR FINAL EXIT. See the section enti- tled 'SYSTEM OVERVIEW' for additional explanation of this requirement. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - LINKING PROGRAMS - - -| |___________________________________________| page 11H We must assume that the application developer understands the use of the MS-DOS linker and the concept of object linking in general. It is beyond the scope of this documentation. Should the user/programmer be unsure of these, he/she is advised to consult the MS-DOS linker documen- tation in the MS-DOS reference before reading further under this sec- tion. No matter which linking method you may choose, the library name of the LSAM system must be specified to the linker for the 'libraries' entry or prompt BEFORE the name(s) of the standard C librar(y/ies), as there are calls to standard C library functions in the LSAM subroutine package which must be resolved. Under NO circumstances should you mix memory model libraries. If you are using compact model, for instance, you should use the compact model LSAM library 'clsam.' The naming convention of the libraries, as sup- plied, follows that of the Microsoft C libraries in its use of the first character of the library name as an abbreviation for the memory model. This should help you to avoid potential linking problems resulting from linking with an incorrect memory model library. If you make such an er- ror, the linker will respond with a 'segment fixup' error message, which should clue you in to the problem. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SUPPORT PROGRAMS - - -| |___________________________________________| page 12H Two 'standalone' support programs are supplied with LSAM. Their purpose is to perform the generation and formatted display/printout of the para- meter files which supply LSAM with the required information about impor- tant attributes of each set of data/index file(s). GENPARM.EXE accepts an ASCII text file of statements describing the characteristics of a data (hereafter referred to as 'base') file and its related index/indices (there may be more than one index per 'base' file) and generates a binary image file in the format required by LSAM to open and process the base and its related index/indices. The syntax of these statements is described in detail below. Usage is: genparm [d:][\pathname\]filename[.txt] where d: is drive (optional) pathname is pathname (optional) filename is parm filename (required) .txt is extension (assumed) Using the syntax rules described below, genparm will produce the file [d:][\pathname\]filename.bin which will be used by LSAM at base/index file open time and in further processing. GENPARM INPUT TEXT SYNTAX RULES There is a single macro command recognized by genparm: lsparm. The 'type' keyword must be specified first for all types. All other keywords are non-positional (EXCEPT subkeyword 'ixname' for the 'index' keyword, which must be the 1st subkeyword for each index file entry). Upper, lower or mixed case input is accepted. Comments may begin any- where on a line, and are preceded by either an asterisk ('*') or a semi- colon (';') as a comment indicator. ALL TEXT FOLLOWING A COMMENT INDI- CATOR IS IGNORED FOR THE REMAINDER OF THE LINE. Use of comments is not required but is encouraged as a means to simplify maintenance. Equal signs and commas are accepted as delimiters for those of you with the IBM (370) macro point of view, but are not required (one or more blanks will do instead). For type=entry, line continuation is indicated by a dash ('-'), and is REQUIRED WHEN THE KEYWORDS/PARMS SPILL OVER BEYOND ONE LINE. Keywords and corresponding parameters (and index subkeywords and their parms) are signified, for each of its three forms, by the value specified for the 'type' keyword: GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SUPPORT PROGRAMS - - -| |___________________________________________| page 13H -------------------------------------------------------------------- parm - macro command keyword parameter/value reqd? --------------------------------------------------------------------------- lsparm type 'begin' (marks beginning of source) | Yes --------------------------------------------------------------------------- lsparm type 'entry' (marks a base/ix entry) | Yes basename valid DOS filename [xxxxxxxx.xxx] | Yes drive valid DOS drive designator [x:] | No path valid DOS pathname [\xxxx[\xxx]\] | No maxlrecl max logical record length GT 0 & LT 65537 | Yes reclaim reuse 'deleted' base file space [YES | no] | No before appending any new data records to | end of base file | *** IGNORED IN 2.02 - RECLAIM ALWAYS 'NO' | recfm base file recd length is [FIXED | variable]| No *** IGNORED IN 2.02 - RECFM ALWAYS 'FIXED' | index ( subkeywords valid only for index keyword ) | Yes *** BEGIN THIS ENTRY/GROUP WITH OPEN PAREN, | END WITH CLOSE PARENTHESIS. | -------------------------------------------| ixname valid DOS filename [xxxxxxxx.xxx]| Yes ('ixname' MARKS BEGINNING OF EACH| INDEX SPECIFICATION, AND SHOULD | BE CODED BEFORE OTHER INDEX SUB-| KEYWORDS) | ixdrive valid DOS drive designator [x:] | No ixpath valid DOS pathname [\xxxx[\xxx]\]| No keys ( offset,len,offset,len ... ) | Yes uniquekey key is unique [YES | no] | No 'no' allows duplicate keys | upgrade insert key on write [YES | no] | No 'no' bypasses index update on | write of record to base file | --------------------------------------------------------------------------- lsparm type 'end' (marks end of source) | Yes --------------------------------------------------------------------------- Alternatives/options are indicated in brackets separated by the symbol '|' with the default indicated in upper case. GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - SUPPORT PROGRAMS - - -| |___________________________________________| page 14H The following is a typical base/(multiple)index file parameter source coding (coded a la IBM 370 mentality w/equal signs and commas, each of which could just as easily be replaced by one or more blanks): *************************************************************** * comment * * documenting use of the base/index files specified here * *************************************************************** lsparm type=begin * either an asterisk (*) ; or a semicolon (;) is a valid comment delimiter * comments may occupy an entire line lsparm type=entry, - ; or the final part of a line * comments need not begin in any particular position basename=auto.dat, - * and they may separate 'continued' lines drive=c:, - * this is a comment path=\c\demo\, - ; this is also a comment maxlrecl=143 - ; use comments to document reclaim=yes, - recfm=fixed, - index=(ixname=auto.i00,ixdrive=c:,ixpath=\c\demo\, - keys=(2,15,18,11,30,1),uniquekey=yes,upgrade=yes, - ixname=auto.i01,ixdrive=c:,ixpath=\c\demo\, - keys=(2,15,18,11,30,1),upgrade=yes,uniquekey=yes) lsparm type=end Here is the same parm file, without the 370 macro characteristics, but equally acceptable to genparm: *************************************************************** * comment * * documenting use of the base/index files specified here * *************************************************************** lsparm type begin * either an asterisk (*) ; or a semicolon (;) is a valid comment delimiter * comments may occupy an entire line lsparm type entry - ; or the final part of a line * comments need not begin in any particular position basename auto.dat - * and they may separate 'continued' lines drive c: - * this is a comment path \c\demo\ - ; this is also a comment maxlrecl 143 - ; use comments to document reclaim yes - recfm fixed - index (ixname auto.i00 ixdrive c: ixpath \c\demo\ - keys (2 15 18 11 30 1) uniquekey yes upgrade yes - ixname auto.i01 ixdrive c: ixpath \c\demo\ - keys (2 15 18 11 30 1) upgrade yes uniquekey yes) lsparm type end END GENPARM INPUT TEXT SYNTAX RULES PARMLIST.EXE will display (on stdout) a formatted listing of the various attributes/parameters in the binary image parameter file generated by genparm.exe above. It is supplied as a convenient method of verifying that the attributes/parameters the user specified for a given base/index set are in fact what was intended. Output may, of course, be redirected wherever desired, such as to a file or printer. Usage is: parmlist [d:][\pathname\]filename[.bin] where d: is drive (optional) pathname is pathname (optional) filename is filename (required) .bin is extension (assumed) GL S A M ___________________________________________ |- - - Lydian Software Access Method - - -| |- - - Free Demo Version 2.02 - - -| |- - - USER DOCUMENTATION - - -| |- - - RUNTIME CONTROL VARIABLES - - -| |___________________________________________| page 15H Two DOS environment variables are supported for control of the LSAM runtime system. They may be set or reset at any time, due to changing needs, and do not require any accompanying program changes. They are most conveniently set in the target user's autoexec.bat or other startup batch file. (See the SET command in the DOS reference). 1) LSAMRTL should be set to the full path name identifying the location of the runtime overlay module 'lsam.rtl.' This variable is REQUIRED. The system will abort the application program if this variable is not found in the environment. 2) LSAMIXALLOC should be set to the number of index control blocks for the runtime system to allocate when it is loaded. This may vary from application to application. For convenience, set it to the largest number of indices (total) used by any of your applications. This number must not exceed 1926, and if it does, you should be running your application under IDMS or DB2 on an IBM 3090, not with this package on a PC. This variable is OPTIONAL, but it DEFAULTS TO 10, which may not be adequate. Therefore, the user is encouraged to set it to his/her 'reasonable' limit. This variable has a di- rect bearing on the ultimate storage requirements of this system. See the section entitled 'STORAGE REQUIREMENTS.' G**** END ****H ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,000+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 721-6104 or (713) 721-5205